/* textstream - a library for rendering scrolling text
 * Copyright (C) 2011 Jack Kelly <jack@jackkelly.name>
 *
 * This library is free software: you can redistribute it and/or
 * modify it under the terms of the GNU Lesser General Public License
 * as published by the Free Software Foundation, either version 3 of
 * the License, or (at your option) any later version.
 *
 * This library is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public License
 * along with this library.  If not, see <http://www.gnu.org/licenses/>.
 */

/**
 ** @node API
 ** @chapter API
 **/

#ifndef TEXTSTREAM_H
#define TEXTSTREAM_H

#include <fake437.h>
#include <glib.h>

struct textstream {
  F437Surface* f437;
  guint speed;
  gboolean needs_newline;
  Uint32 black;
  GQueue events; /* of struct textstream_event* */
};

/**
 ** @deftypefun {struct textstream*} textstream_new @
 **   (SDL_Surface*    @var{surface}, @
 **    const F437Font* @var{font},    @
 **    gint            @var{scale})
 **
 ** Create a @code{struct textstream} that fits as many characters as
 ** possible in @var{surface}, given @var{font} and @var{scale}. Free
 ** with @code{textstream_free} when no longer needed. It does not
 ** take ownership of @var{surface} or @var{font}, which both need to
 ** last longer than the returned @code{struct textstream*}.
 **
 ** A textstream is basically a queue of events: text to show, color
 ** changes and newlines.
 **
 ** @code{NULL} will only be returned if @var{surface} is
 ** @code{NULL}. Allocation failures result in an abort.
 **
 ** @end deftypefun
 **/
struct textstream* textstream_new(SDL_Surface* surface,
                                  const F437Font* font,
                                  gint scale);
/**
 ** @deftypefun SDL_Surface* textstream_free @
 **   (struct textstream* @var{ts})
 **
 ** Frees the textstream but returns the wrapped surface passed into
 ** the constructor.
 **
 ** @end deftypefun
 **/
SDL_Surface* textstream_free(struct textstream* ts);

/**
 ** @deftypefun void textstream_add @
 **   (struct textstream* @var{ts}, @
 **    const gchar*       @var{str})
 **
 ** Add @var{str} to the queue of strings to print. An internal copy
 ** of @var{str} is taken. Because libfake437 includes glyphs for
 ** characters 0-31, escape sequences will not work. Use
 ** @code{textstream_nl} to insert a newline.
 **
 ** @end deftypefun
 **/
void textstream_add(struct textstream* ts, const gchar* str);

/**
 ** @deftypefun void textstream_add_instant @
 **   (struct textstream* @var{ts},         @
 **    const gchar*       @var{str})
 **
 ** Add @var{str} to the queue of strings to print. When the first
 ** character of @var{str} is printed, the entire string will be
 ** printed. Consecutive calls to @code{textstream_add_instant} will
 ** be rendered by separate calles to @code{textstream_update}.
 **
 ** @end deftypefun
 **/
void textstream_add_instant(struct textstream* ts, const gchar* str);

/**
 ** @deftypefun void textstream_fg  @
 **   (struct textstream* @var{ts}, @
 **    F437Color          @var{fg})
 ** @deftypefunx void textstream_bg @
 **   (struct textstream* @var{ts}, @
 **    F437Color          @var{bg})
 **
 ** Change the foreground or background color of printed text. The
 ** change takes effect after all text before it is processed.
 **
 ** @end deftypefun
 **/
void textstream_fg(struct textstream* ts, F437Color fg);
void textstream_bg(struct textstream* ts, F437Color bg);

/**
 ** @deftypefun void textstream_newline @
 **   (struct textstream* @var{ts})
 **
 ** Enqueue a newline in the text stream.
 **
 ** @end deftypefun
 **/
void textstream_newline(struct textstream* ts);

/**
 ** @deftypefun void textstream_clear @
 **   (struct textstream* @var{ts})
 **
 ** Instantly clear the rendered screen; new text will be printed at
 ** the top-left corner.
 **
 ** @end deftypefun
 **/
void textstream_clear(struct textstream* ts);

/**
 ** @deftypefun gboolean textstream_update @
 **   (struct textstream* @var{ts})
 **
 ** Print something to the wrapped surface. Usually prints one
 ** character, unless it is printing text added with
 ** @code{textstream_add_instant}. Return @code{TRUE} iff something
 ** was printed.
 **
 ** @end deftypefun
 **/
gboolean textstream_update(struct textstream* ts);

#endif
